package org.twdata.pipeline.stage;

import org.twdata.pipeline.*;

// SAX imports:
import org.xml.sax.Attributes;
import org.xml.sax.ContentHandler;
import org.xml.sax.Locator;
import org.xml.sax.SAXException;
import org.xml.sax.ext.LexicalHandler;

/**
 *  This convenience class implements all Transformer methods to make it easier
 *  to create transformers. By default, all SAX events are simply passed on to
 *  the next XMLConsumer.
 */
public abstract class AbstractTransformer implements Transformer {

    /**  The <code>ContentHandler</code> receiving SAX events. */
    protected ContentHandler contentHandler;

    /**  The <code>LexicalHandler</code> receiving SAX events. */
    protected LexicalHandler lexicalHandler;
    
    /**  A unique id for this stage */
    protected String id;


    /**
     *  Gets the id
     *
     *@return    The id value
     */
     public String getId() {
        return id;   
     }
    
    /**
     *  Sets the id
     *
     *@param  id  The unique id
     */
     public void setId(String id) {
         this.id = id;
     }


    /**
     *  Set the <code>ContentHandler</code> that will receive XML data. <br>
     *  Subclasses may retrieve this <code>ContentHandler</code> instance
     *  accessing the protected <code>super.contentHandler</code> field.
     *
     *@param  consumer               The new consumer
     *@exception  PipelineException  If anything goes wrong
     */
    public void setConsumer(XMLConsumer consumer)
        throws PipelineException {
        this.contentHandler = consumer;
        this.lexicalHandler = consumer;
    }


    /**
     *  Sets up the instance for a new pipeline
     *
     *@param  ctx                    The current context
     *@exception  PipelineException  If anything goes wrong
     */
    public void setup(PipelineContext ctx)
        throws PipelineException { }


    /**  Recycles the instance */
    public void recycle() {
        contentHandler = null;
        lexicalHandler = null;
    }


    /**
     *  Receive an object for locating the origin of SAX document events.
     *
     *@param  locator  An object that can return the location of any SAX
     *      document event.
     */
    public void setDocumentLocator(Locator locator) {
        if (contentHandler != null) {
            contentHandler.setDocumentLocator(locator);
        }
    }


    /**
     *  Receive notification of the beginning of a document.
     *
     *@exception  SAXException  If anything goes wrong
     */
    public void startDocument()
        throws SAXException {
        if (contentHandler != null) {
            contentHandler.startDocument();
        }
    }


    /**
     *  Receive notification of the end of a document.
     *
     *@exception  SAXException  If anything goes wrong
     */
    public void endDocument()
        throws SAXException {
        if (contentHandler != null) {
            contentHandler.endDocument();
        }
    }


    /**
     *  Begin the scope of a prefix-URI Namespace mapping.
     *
     *@param  prefix            The Namespace prefix being declared.
     *@param  uri               The Namespace URI the prefix is mapped to.
     *@exception  SAXException  If anything goes wrong
     */
    public void startPrefixMapping(String prefix, String uri)
        throws SAXException {
        if (contentHandler != null) {
            contentHandler.startPrefixMapping(prefix, uri);
        }
    }


    /**
     *  End the scope of a prefix-URI mapping.
     *
     *@param  prefix            The prefix that was being mapping.
     *@exception  SAXException  If anything goes wrong
     */
    public void endPrefixMapping(String prefix)
        throws SAXException {
        if (contentHandler != null) {
            contentHandler.endPrefixMapping(prefix);
        }
    }


    /**
     *  Receive notification of the beginning of an element.
     *
     *@param  uri               The Namespace URI, or the empty string if the
     *      element has no Namespace URI or if Namespace processing is not being
     *      performed.
     *@param  loc               The local name (without prefix), or the empty
     *      string if Namespace processing is not being performed.
     *@param  raw               The raw XML 1.0 name (with prefix), or the empty
     *      string if raw names are not available.
     *@param  a                 The attributes attached to the element. If there
     *      are no attributes, it shall be an empty Attributes object.
     *@exception  SAXException  If anything goes wrong
     */
    public void startElement(String uri, String loc, String raw, Attributes a)
        throws SAXException {

        if (contentHandler != null) {
            contentHandler.startElement(uri, loc, raw, a);
        }
    }


    /**
     *  Receive notification of the end of an element.
     *
     *@param  uri               The Namespace URI, or the empty string if the
     *      element has no Namespace URI or if Namespace processing is not being
     *      performed.
     *@param  loc               The local name (without prefix), or the empty
     *      string if Namespace processing is not being performed.
     *@param  raw               The raw XML 1.0 name (with prefix), or the empty
     *      string if raw names are not available.
     *@exception  SAXException  If anything goes wrong
     */
    public void endElement(String uri, String loc, String raw)
        throws SAXException {
        if (contentHandler != null) {
            contentHandler.endElement(uri, loc, raw);
        }
    }


    /**
     *  Receive notification of character data.
     *
     *@param  c                 The characters from the XML document.
     *@param  start             The start position in the array.
     *@param  len               The number of characters to read from the array.
     *@exception  SAXException  If anything goes wrong
     */
    public void characters(char c[], int start, int len)
        throws SAXException {
        if (contentHandler != null) {
            contentHandler.characters(c, start, len);
        }
    }


    /**
     *  Receive notification of ignorable whitespace in element content.
     *
     *@param  c                 The characters from the XML document.
     *@param  start             The start position in the array.
     *@param  len               The number of characters to read from the array.
     *@exception  SAXException  If anything goes wrong
     */
    public void ignorableWhitespace(char c[], int start, int len)
        throws SAXException {
        if (contentHandler != null) {
            contentHandler.ignorableWhitespace(c, start, len);
        }
    }


    /**
     *  Receive notification of a processing instruction.
     *
     *@param  target            The processing instruction target.
     *@param  data              The processing instruction data, or null if none
     *      was supplied.
     *@exception  SAXException  If anything goes wrong
     */
    public void processingInstruction(String target, String data)
        throws SAXException {
        if (contentHandler != null) {
            contentHandler.processingInstruction(target, data);
        }
    }


    /**
     *  Receive notification of a skipped entity.
     *
     *@param  name              The name of the skipped entity. If it is a
     *      parameter entity, the name will begin with '%'.
     *@exception  SAXException  If anything goes wrong
     */
    public void skippedEntity(String name)
        throws SAXException {
        if (contentHandler != null) {
            contentHandler.skippedEntity(name);
        }
    }


    /**
     *  Report the start of DTD declarations, if any.
     *
     *@param  name              The document type name.
     *@param  publicId          The declared public identifier for the external
     *      DTD subset, or null if none was declared.
     *@param  systemId          The declared system identifier for the external
     *      DTD subset, or null if none was declared.
     *@exception  SAXException  If anything goes wrong
     */
    public void startDTD(String name, String publicId, String systemId)
        throws SAXException {
        if (lexicalHandler != null) {
            lexicalHandler.startDTD(name, publicId, systemId);
        }
    }


    /**
     *  Report the end of DTD declarations.
     *
     *@exception  SAXException  If anything goes wrong
     */
    public void endDTD()
        throws SAXException {
        if (lexicalHandler != null) {
            lexicalHandler.endDTD();
        }
    }


    /**
     *  Report the beginning of an entity.
     *
     *@param  name              The name of the entity. If it is a parameter
     *      entity, the name will begin with '%'.
     *@exception  SAXException  If anything goes wrong
     */
    public void startEntity(String name)
        throws SAXException {
        if (lexicalHandler != null) {
            lexicalHandler.startEntity(name);
        }
    }


    /**
     *  Report the end of an entity.
     *
     *@param  name              The name of the entity that is ending.
     *@exception  SAXException  If anything goes wrong
     */
    public void endEntity(String name)
        throws SAXException {
        if (lexicalHandler != null) {
            lexicalHandler.endEntity(name);
        }
    }


    /**
     *  Report the start of a CDATA section.
     *
     *@exception  SAXException  If anything goes wrong
     */
    public void startCDATA()
        throws SAXException {
        if (lexicalHandler != null) {
            lexicalHandler.startCDATA();
        }
    }


    /**
     *  Report the end of a CDATA section.
     *
     *@exception  SAXException  If anything goes wrong
     */
    public void endCDATA()
        throws SAXException {
        if (lexicalHandler != null) {
            lexicalHandler.endCDATA();
        }
    }


    /**
     *  Report an XML comment anywhere in the document.
     *
     *@param  ch                An array holding the characters in the comment.
     *@param  start             The starting position in the array.
     *@param  len               The number of characters to use from the array.
     *@exception  SAXException  If anything goes wrong
     */
    public void comment(char ch[], int start, int len)
        throws SAXException {
        if (lexicalHandler != null) {
            lexicalHandler.comment(ch, start, len);
        }
    }
}

